[−][src]Crate chacha20

The ChaCha20 stream cipher (RFC 8439)

ChaCha20 is a lightweight stream cipher which is amenable to fast, constant-time implementations in software. It improves upon the previous Salsa20 stream cipher, providing increased per-round diffusion with no cost to performance.

Cipher functionality is accessed using traits from re-exported stream-cipher crate.

This crate contains three variants of ChaCha20:

  • ChaCha20: standard IETF variant with 96-bit nonce
  • ChaCha20Legacy: (gated under the legacy feature) "djb" variant with 64-bit nonce
  • ChaCha8 / ChaCha12: reduced round variants of ChaCha20
  • XChaCha20: (gated under the xchacha20 feature) 192-bit extended nonce variant

Security Warning

This crate does not ensure ciphertexts are authentic, which can lead to serious vulnerabilities if used incorrectly!

USE AT YOUR OWN RISK!

Diagram

This diagram illustrates the ChaCha quarter round function. Each round consists of four quarter-rounds:

Legend:

  • ⊞ add
  • ‹‹‹ rotate
  • ⊕ xor

Usage

use chacha20::{ChaCha20, Key, Nonce};
use chacha20::stream_cipher::{NewStreamCipher, SyncStreamCipher, SyncStreamCipherSeek};

let mut data = [1, 2, 3, 4, 5, 6, 7];

let key = Key::from_slice(b"an example very very secret key.");
let nonce = Nonce::from_slice(b"secret nonce");

// create cipher instance
let mut cipher = ChaCha20::new(&key, &nonce);

// apply keystream (encrypt)
cipher.apply_keystream(&mut data);
assert_eq!(data, [73, 98, 234, 202, 73, 143, 0]);

// seek to the keystream beginning and apply it again to the `data` (decrypt)
cipher.seek(0);
cipher.apply_keystream(&mut data);
assert_eq!(data, [1, 2, 3, 4, 5, 6, 7]);

Re-exports

pub use stream_cipher;

Structs

ChaCha8Rngfeature="rng"

Random number generator over the ChaCha8 stream cipher.

ChaCha8RngCorefeature="rng"

Core random number generator, for use with rand_core::block::BlockRng

ChaCha12Rngfeature="rng"

Random number generator over the ChaCha12 stream cipher.

ChaCha12RngCorefeature="rng"

Core random number generator, for use with rand_core::block::BlockRng

ChaCha20Legacyfeature="legacy"

The ChaCha20 stream cipher (legacy "djb" construction with 64-bit nonce).

ChaCha20Rngfeature="rng"

Random number generator over the ChaCha20 stream cipher.

ChaCha20RngCorefeature="rng"

Core random number generator, for use with rand_core::block::BlockRng

Cipher

ChaCha family stream cipher, generic around a number of rounds.

XChaCha20feature="xchacha20"

XChaCha20 is a ChaCha20 variant with an extended 192-bit (24-byte) nonce.

Constants

BLOCK_SIZE

Size of a ChaCha20 block in bytes

KEY_SIZE

Size of a ChaCha20 key in bytes

MAX_BLOCKS

Maximum number of blocks that can be encrypted with ChaCha20 before the counter overflows.

Type Definitions

ChaCha8

ChaCha8 stream cipher (reduced-round variant of ChaCha20 with 8 rounds)

ChaCha12

ChaCha12 stream cipher (reduced-round variant of ChaCha20 with 12 rounds)

ChaCha20

ChaCha20 stream cipher (RFC 8439 version with 96-bit nonce)

Key

ChaCha20 key type (256-bits/32-bytes)

LegacyNoncefeature="legacy"

Size of the nonce for the legacy ChaCha20 stream cipher

Nonce

Nonce type (96-bits/12-bytes)

XNoncefeature="xchacha20"

EXtended ChaCha20 nonce (192-bits/24-bytes)